agent-tools-interface 0.7.11

Agent Tools Interface — secure CLI for AI agent tool execution
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# ati-client

Python SDK for [ATI](https://github.com/Parcha-ai/ati) (Agent Tools Interface) — orchestrator provisioning and JWT token utilities.

## Install

```bash
pip install ati-client
```

## Quick Start

### Orchestrator Provisioning

```python
from ati import AtiOrchestrator

orch = AtiOrchestrator(
    proxy_url="https://ati-proxy.example.com",
    secret="17332cf135d362f79a2ed700b13e1215978be1d6ae6e133d25b6b3f21fa10299",
)

# Generate env vars to inject into a sandboxed agent
env_vars = orch.provision_sandbox(
    agent_id=f"sandbox:{sandbox_id}",
    tools=["finnhub_quote", "web_search", "github:*"],
    skills=["financial-analysis"],
    ttl_seconds=7200,
    rate={"tool:github:*": "10/hour"},
)

# env_vars = {
#     "ATI_PROXY_URL": "https://ati-proxy.example.com",
#     "ATI_SESSION_TOKEN": "eyJ...",
# }
```

### Token Utilities

```python
from ati import issue_token, validate_token, inspect_token

# Issue a token
token = issue_token(
    secret="17332cf135d362f79a...",
    sub="agent-7",
    scope="tool:web_search tool:finnhub_quote",
    ttl_seconds=3600,
)

# Validate (checks signature, expiry, audience)
claims = validate_token(token, secret="17332cf135d362f79a...")
print(claims.sub)      # "agent-7"
print(claims.scopes()) # ["tool:web_search", "tool:finnhub_quote"]

# Inspect without validation (debugging)
claims = inspect_token(token)
```

### Scope Utilities

```python
from ati import build_scope_string, check_scope, matches_wildcard

# Build scope strings
scope = build_scope_string(
    tools=["web_search", "github:*"],
    skills=["research-*"],
    extra=["help"],
)
# "tool:web_search tool:github:* skill:research-* help"

# Check if a tool is allowed
check_scope("tool:github:search_repos", ["tool:github:*"])  # True
check_scope("tool:secret_api", ["tool:web_search"])            # False

# Wildcard matching
matches_wildcard("tool:github:search", "tool:github:*")  # True
matches_wildcard("anything", "*")                           # True
```

## JWT Format

Tokens are HS256-signed JWTs compatible with the ATI Rust proxy. The secret must be a hex-encoded 32-byte key (64 hex characters).

Claims payload:

```json
{
  "sub": "agent-7",
  "aud": "ati-proxy",
  "iat": 1700000000,
  "exp": 1700003600,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "iss": "ati-orchestrator",
  "scope": "tool:web_search tool:github:*",
  "ati": {
    "v": 1,
    "rate": {
      "tool:github:*": "10/hour"
    }
  }
}
```

## Development

```bash
cd ati-client
pip install -e ".[dev]"
pytest
```