Name | agentvisa JSON |
Version |
0.1.0
JSON |
| download |
home_page | None |
Summary | The official Python SDK for the AgentVisa API. |
upload_time | 2025-07-30 22:40:47 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.13 |
license | MIT |
keywords |
agent
agentvisa
api
delegation
sdk
|
VCS |
 |
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# AgentVisa Python SDK
[](https://github.com/AgentVisa/agentvisa-python/actions)
[](https://badge.fury.io/py/agentvisa)
[](https://pypi.org/project/agentvisa/)
The official Python SDK for the [AgentVisa API](https://agentvisa.dev).
## Quick Start
```bash
pip install agentvisa
```
```python
import agentvisa
# Initialize the SDK
agentvisa.init(api_key="your-api-key")
# Create a delegation
delegation = agentvisa.create_delegation(
end_user_identifier="user123",
scopes=["read", "write"]
)
print(f"Created delegation: {delegation['id']}")
```
## Installation
### Using pip
```bash
pip install agentvisa
```
### Using uv
```bash
uv add agentvisa
```
## Authentication
Get your API key from the [AgentVisa Dashboard](https://agentvisa.dev/dashboard).
```python
import agentvisa
agentvisa.init(api_key="av_1234567890abcdef")
```
## Usage
### Simple Interface (Recommended)
For most use cases, use the simple global interface:
```python
import agentvisa
# Initialize once
agentvisa.init(api_key="your-api-key")
# Create delegations
delegation = agentvisa.create_delegation(
end_user_identifier="user123",
scopes=["read", "write", "admin"],
expires_in=7200 # 2 hours
)
```
### Client Interface
For advanced use cases or multiple configurations:
```python
from agentvisa import AgentVisaClient
# Create client instance
client = AgentVisaClient(api_key="your-api-key")
# Use the client
delegation = client.delegations.create(
end_user_identifier="user123",
scopes=["read", "write"],
expires_in=3600
)
```
## Integrating with LangChain
You can easily secure LangChain agents by creating a custom tool that wraps AgentVisa. This ensures that every time an agent needs to perform a privileged action, it acquires a fresh, scoped, short-lived credential tied to the end-user.
This example shows how to create a secure "email sending" tool.
### 1. Create the AgentVisa-powered Tool
The tool's `_run` method will call `agentvisa.create_delegation` to get a secure token just before it performs its action.
```python
from langchain.tools import BaseTool
import agentvisa
# Initialize AgentVisa once in your application
agentvisa.init(api_key="your-api-key")
class SecureEmailTool(BaseTool):
name = "send_email"
description = "Use this tool to send an email."
def _run(self, to: str, subject: str, body: str, user_id: str):
"""Sends an email securely using an AgentVisa token."""
# 1. Get a short-lived, scoped credential from AgentVisa
try:
delegation = agentvisa.create_delegation(
end_user_identifier=user_id,
scopes=["send:email"]
)
token = delegation.get('token')
print(f"Successfully acquired AgentVisa for user '{user_id}' with scope 'send:email'")
except Exception as e:
return f"Error: Could not acquire AgentVisa. {e}"
# 2. Use the token to call your internal, secure email API
# Your internal API would verify this token before sending the email.
print(f"Calling internal email service with token: {token[:15]}...")
# response = requests.post(
# "https://internal-api.yourcompany.com/send-email",
# headers={"Authorization": f"Bearer {token}"},
# json={"to": to, "subject": subject, "body": body}
# )
# For this example, we'll simulate a successful call
return "Email sent successfully."
async def _arun(self, to: str, subject: str, body: str, user_id: str):
# LangChain requires an async implementation for tools
raise NotImplementedError("SecureEmailTool does not support async")
```
### 2. Add the Tool to your Agent
Now, you can provide this tool to your LangChain agent. When the agent decides to use the `send_email` tool, it will automatically generate a new, auditable AgentVisa.
```python
from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI
# Initialize your LLM
llm = ChatOpenAI(model_name="gpt-4o", temperature=0)
# Create an instance of your secure tool
tools = [SecureEmailTool()]
# Initialize the agent
agent = initialize_agent(
tools,
llm,
agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
verbose=True
)
# Run the agent
# The agent will correctly parse the user_id and pass it to the tool
agent.run("Please send an email to team@example.com with the subject 'Project Update' and body 'The new feature is live.' for user_id 'user_anne'.")
```
This pattern provides the perfect combination of LangChain's powerful reasoning capabilities with AgentVisa's secure, auditable credentialing system.
## API Reference
### Delegations
#### `create_delegation(end_user_identifier, scopes, expires_in=3600)`
Create a new agent delegation.
**Parameters:**
- `end_user_identifier` (str): Unique identifier for the end user
- `scopes` (List[str]): List of permission scopes
- `expires_in` (int): Expiration time in seconds (default: 3600)
**Returns:**
Dict containing delegation details including `id`, `token`, and `expires_at`.
**Example:**
```python
delegation = agentvisa.create_delegation(
end_user_identifier="user123",
scopes=["read", "write"],
expires_in=7200
)
```
## Error Handling
The SDK raises standard Python exceptions:
```python
import agentvisa
from requests.exceptions import HTTPError
try:
agentvisa.init(api_key="invalid-key")
delegation = agentvisa.create_delegation("user123", ["read"])
except ValueError as e:
print(f"Invalid input: {e}")
except HTTPError as e:
print(f"API error: {e}")
except Exception as e:
print(f"SDK not initialized: {e}")
```
## Development
### Setup
```bash
git clone https://github.com/your-org/agentvisa-python.git
cd agentvisa-python
make install
```
### Testing
```bash
make test
```
### Linting
```bash
make lint
```
### Type Checking
```bash
make typecheck
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`make test`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## Support
- [Documentation](https://agentvisa.dev/docs)
- [Issues](https://github.com/AgentVisa/agentvisa-python/issues)
- [Discord Community](https://discord.gg/ZupkwFbvqC)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "agentvisa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "agent, agentvisa, api, delegation, sdk",
"author": null,
"author_email": "Chris Clapham <chris@agentvisa.dev>",
"download_url": "https://files.pythonhosted.org/packages/06/eb/14c7e2e4bb66784607f8c3f7fe8da9173f9cbda34f2a5b66b3b057857052/agentvisa-0.1.0.tar.gz",
"platform": null,
"description": "# AgentVisa Python SDK\n\n[](https://github.com/AgentVisa/agentvisa-python/actions)\n[](https://badge.fury.io/py/agentvisa)\n[](https://pypi.org/project/agentvisa/)\n\nThe official Python SDK for the [AgentVisa API](https://agentvisa.dev).\n\n## Quick Start\n\n```bash\npip install agentvisa\n```\n\n```python\nimport agentvisa\n\n# Initialize the SDK\nagentvisa.init(api_key=\"your-api-key\")\n\n# Create a delegation\ndelegation = agentvisa.create_delegation(\n end_user_identifier=\"user123\",\n scopes=[\"read\", \"write\"]\n)\nprint(f\"Created delegation: {delegation['id']}\")\n```\n\n## Installation\n\n### Using pip\n```bash\npip install agentvisa\n```\n\n### Using uv\n```bash\nuv add agentvisa\n```\n\n## Authentication\n\nGet your API key from the [AgentVisa Dashboard](https://agentvisa.dev/dashboard).\n\n```python\nimport agentvisa\n\nagentvisa.init(api_key=\"av_1234567890abcdef\")\n```\n\n## Usage\n\n### Simple Interface (Recommended)\n\nFor most use cases, use the simple global interface:\n\n```python\nimport agentvisa\n\n# Initialize once\nagentvisa.init(api_key=\"your-api-key\")\n\n# Create delegations\ndelegation = agentvisa.create_delegation(\n end_user_identifier=\"user123\",\n scopes=[\"read\", \"write\", \"admin\"],\n expires_in=7200 # 2 hours\n)\n```\n\n### Client Interface\n\nFor advanced use cases or multiple configurations:\n\n```python\nfrom agentvisa import AgentVisaClient\n\n# Create client instance\nclient = AgentVisaClient(api_key=\"your-api-key\")\n\n# Use the client\ndelegation = client.delegations.create(\n end_user_identifier=\"user123\",\n scopes=[\"read\", \"write\"],\n expires_in=3600\n)\n```\n\n## Integrating with LangChain\n\nYou can easily secure LangChain agents by creating a custom tool that wraps AgentVisa. This ensures that every time an agent needs to perform a privileged action, it acquires a fresh, scoped, short-lived credential tied to the end-user.\n\nThis example shows how to create a secure \"email sending\" tool.\n\n### 1. Create the AgentVisa-powered Tool\n\nThe tool's `_run` method will call `agentvisa.create_delegation` to get a secure token just before it performs its action.\n\n```python\nfrom langchain.tools import BaseTool\nimport agentvisa\n\n# Initialize AgentVisa once in your application\nagentvisa.init(api_key=\"your-api-key\")\n\nclass SecureEmailTool(BaseTool):\n name = \"send_email\"\n description = \"Use this tool to send an email.\"\n\n def _run(self, to: str, subject: str, body: str, user_id: str):\n \"\"\"Sends an email securely using an AgentVisa token.\"\"\"\n \n # 1. Get a short-lived, scoped credential from AgentVisa\n try:\n delegation = agentvisa.create_delegation(\n end_user_identifier=user_id,\n scopes=[\"send:email\"]\n )\n token = delegation.get('token')\n print(f\"Successfully acquired AgentVisa for user '{user_id}' with scope 'send:email'\")\n except Exception as e:\n return f\"Error: Could not acquire AgentVisa. {e}\"\n\n # 2. Use the token to call your internal, secure email API\n # Your internal API would verify this token before sending the email.\n print(f\"Calling internal email service with token: {token[:15]}...\")\n # response = requests.post(\n # \"https://internal-api.yourcompany.com/send-email\",\n # headers={\"Authorization\": f\"Bearer {token}\"},\n # json={\"to\": to, \"subject\": subject, \"body\": body}\n # )\n \n # For this example, we'll simulate a successful call\n return \"Email sent successfully.\"\n\n async def _arun(self, to: str, subject: str, body: str, user_id: str):\n # LangChain requires an async implementation for tools\n raise NotImplementedError(\"SecureEmailTool does not support async\")\n```\n\n### 2. Add the Tool to your Agent\n\nNow, you can provide this tool to your LangChain agent. When the agent decides to use the `send_email` tool, it will automatically generate a new, auditable AgentVisa.\n\n```python\nfrom langchain.agents import initialize_agent, AgentType\nfrom langchain.chat_models import ChatOpenAI\n\n# Initialize your LLM\nllm = ChatOpenAI(model_name=\"gpt-4o\", temperature=0)\n\n# Create an instance of your secure tool\ntools = [SecureEmailTool()]\n\n# Initialize the agent\nagent = initialize_agent(\n tools,\n llm,\n agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,\n verbose=True\n)\n\n# Run the agent\n# The agent will correctly parse the user_id and pass it to the tool\nagent.run(\"Please send an email to team@example.com with the subject 'Project Update' and body 'The new feature is live.' for user_id 'user_anne'.\")\n```\n\nThis pattern provides the perfect combination of LangChain's powerful reasoning capabilities with AgentVisa's secure, auditable credentialing system.\n\n## API Reference\n\n### Delegations\n\n#### `create_delegation(end_user_identifier, scopes, expires_in=3600)`\n\nCreate a new agent delegation.\n\n**Parameters:**\n- `end_user_identifier` (str): Unique identifier for the end user\n- `scopes` (List[str]): List of permission scopes\n- `expires_in` (int): Expiration time in seconds (default: 3600)\n\n**Returns:**\nDict containing delegation details including `id`, `token`, and `expires_at`.\n\n**Example:**\n```python\ndelegation = agentvisa.create_delegation(\n end_user_identifier=\"user123\",\n scopes=[\"read\", \"write\"],\n expires_in=7200\n)\n```\n\n## Error Handling\n\nThe SDK raises standard Python exceptions:\n\n```python\nimport agentvisa\nfrom requests.exceptions import HTTPError\n\ntry:\n agentvisa.init(api_key=\"invalid-key\")\n delegation = agentvisa.create_delegation(\"user123\", [\"read\"])\nexcept ValueError as e:\n print(f\"Invalid input: {e}\")\nexcept HTTPError as e:\n print(f\"API error: {e}\")\nexcept Exception as e:\n print(f\"SDK not initialized: {e}\")\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/your-org/agentvisa-python.git\ncd agentvisa-python\nmake install\n```\n\n### Testing\n\n```bash\nmake test\n```\n\n### Linting\n\n```bash\nmake lint\n```\n\n### Type Checking\n\n```bash\nmake typecheck\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`make test`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Support\n\n- [Documentation](https://agentvisa.dev/docs)\n- [Issues](https://github.com/AgentVisa/agentvisa-python/issues)\n- [Discord Community](https://discord.gg/ZupkwFbvqC)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The official Python SDK for the AgentVisa API.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/AgentVisa/agentvisa-python/issues",
"Documentation": "https://docs.agentvisa.dev",
"Homepage": "https://agentvisa.dev",
"Repository": "https://github.com/AgentVisa/agentvisa-python"
},
"split_keywords": [
"agent",
" agentvisa",
" api",
" delegation",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85575dd1cbf48fbd17a0c4d238b166f448d55d65166212ac34c61c9cc6e278f0",
"md5": "75e49d9e1d739f95e256aeb20dabf6db",
"sha256": "6aca6d56d14e95f40cdb049959aa1854f13a452dfbe12e4044b6fa272edb71a3"
},
"downloads": -1,
"filename": "agentvisa-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75e49d9e1d739f95e256aeb20dabf6db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 6953,
"upload_time": "2025-07-30T22:40:45",
"upload_time_iso_8601": "2025-07-30T22:40:45.505523Z",
"url": "https://files.pythonhosted.org/packages/85/57/5dd1cbf48fbd17a0c4d238b166f448d55d65166212ac34c61c9cc6e278f0/agentvisa-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "06eb14c7e2e4bb66784607f8c3f7fe8da9173f9cbda34f2a5b66b3b057857052",
"md5": "28407d2e0c97a8bf6dc1e5f1eec435b0",
"sha256": "d8454d570266a0529cef13538303d7bb6c06f63e780ae1239c5f4b0a516c11ea"
},
"downloads": -1,
"filename": "agentvisa-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "28407d2e0c97a8bf6dc1e5f1eec435b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 22876,
"upload_time": "2025-07-30T22:40:47",
"upload_time_iso_8601": "2025-07-30T22:40:47.093452Z",
"url": "https://files.pythonhosted.org/packages/06/eb/14c7e2e4bb66784607f8c3f7fe8da9173f9cbda34f2a5b66b3b057857052/agentvisa-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 22:40:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AgentVisa",
"github_project": "agentvisa-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agentvisa"
}