agentvisa


Nameagentvisa JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryThe official Python SDK for the AgentVisa API.
upload_time2025-07-30 22:40:47
maintainerNone
docs_urlNone
authorNone
requires_python>=3.13
licenseMIT
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

[![Tests](https://github.com/AgentVisa/agentvisa-python/workflows/Tests/badge.svg)](https://github.com/AgentVisa/agentvisa-python/actions)
[![PyPI version](https://badge.fury.io/py/agentvisa.svg)](https://badge.fury.io/py/agentvisa)
[![Python Support](https://img.shields.io/pypi/pyversions/agentvisa.svg)](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[![Tests](https://github.com/AgentVisa/agentvisa-python/workflows/Tests/badge.svg)](https://github.com/AgentVisa/agentvisa-python/actions)\n[![PyPI version](https://badge.fury.io/py/agentvisa.svg)](https://badge.fury.io/py/agentvisa)\n[![Python Support](https://img.shields.io/pypi/pyversions/agentvisa.svg)](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"
}
        
Elapsed time: 1.15222s