Quickstart

Declare a tool

A tool for an API Charter has never seen, with your own rules on it. httpbin.org stands in for the API: it echoes back the request it received, so everything on this page runs with no account.

Describe the arguments, and your rules

refund.py

from typing import Annotated, Literal

from pydantic import BaseModel, Field, field_validator
from charter import Body, Gloss


class CreateRefund(BaseModel):
    charge: Annotated[str, Body()] = Field(description="The charge to refund.")
    amount: Annotated[
        int,
        Body(),
        Gloss("Cents, not dollars: $15.00 is 1500."),
    ] = Field(gt=0, le=10_000, description="How much to refund, in the smallest currency unit.")
    reason: Annotated[Literal["duplicate", "requested_by_customer"], Body()] = Field(
        description="Why the charge is being refunded."
    )
    currency: Annotated[str, Body()] = Field("usd", description="Three-letter ISO currency code.")

    @field_validator("charge")
    @classmethod
    def a_charge(cls, value: str) -> str:
        if not value.startswith("ch_"):
            raise ValueError("refund a charge id (ch_...), not a customer or an invoice")
        return value

Body() says where each field goes in the request; Query(), Path() and Header() are the others. Everything else on the model is a rule of yours, on top of the API’s: le=10_000 caps a refund at $100, the Literal leaves out "fraudulent" although the API accepts it, and the validator is any check you can write in Python. The Gloss is softer: a tip the model reads beside the field’s own description, which nothing enforces.

Build a factory

The factory carries everything shared across the tools of one API: the base URL, the credential, and the conventions its wire format follows.

refund.py

from charter import api_key_tool_factory

payments = api_key_tool_factory(
    pack="payments",
    base_url="https://httpbin.org/anything/",
    api_key_headers={"Authorization": "Bearer sk_test_123"},
)

pack is a prefix for your tools’ names, so this one reaches the model as payments_refund. For an API that takes an OAuth token, oauth_tool_factory takes the same arguments and a credential provider.

Declare the tool

Point the arguments at an endpoint.

refund.py

refund = payments(
    name="refund",
    description="Refund a charge.",
    method="POST",
    url_template="v1/refunds",
    args_schema=CreateRefund,
)

Call it

refund.py

sent = refund.invoke({"charge": "ch_3MmlLr", "amount": 1500, "reason": "duplicate"})
print(sent["method"], sent["url"])
print(sent["json"])

POST https://httpbin.org/anything/v1/refunds
{'amount': 1500, 'charge': 'ch_3MmlLr', 'currency': 'usd', 'reason': 'duplicate'}

The key went out in the Authorization header and the model never saw it. A declaration also carries wire format, field policy and failure that arrives as HTTP 200; the wire contract is where those go.

Break a rule

Now the call a model gets wrong: a customer id where a charge belongs, $150, and a reason you ruled out.

refund.py

from charter import ToolValidationError

try:
    refund.invoke({"charge": "cus_9s6XKz", "amount": 15000, "reason": "fraudulent"})
except ToolValidationError as refused:
    print(refused)

Validation error:
- **charge**: Value error, refund a charge id (ch_...), not a customer or an invoice (got 'cus_9s6XKz')
- **amount**: Input should be less than or equal to 10000 (got 15000)
- **reason**: Input should be 'duplicate' or 'requested_by_customer' (got 'fraudulent')

Nothing was sent. Every rule, the API’s and yours, runs before any request, so a call that breaks one never reaches the API. In an agent, this message is what the model gets back as the tool’s result, naming each field and what it sent, so it can fix the call or stop. Charter never improvises. And since no request is made, every rule can be tested offline with plain unit tests.

Pin a value, and see what the model sees

A pin removes a field from what the model sees and sends a fixed value on every call. Then print the boundary: it is computed from the same declarations the runtime executes, so it cannot drift from what actually happens.

refund.py

from charter import format_egress_map

refund_usd = refund.derived(name="refund_usd", pin={"currency": "usd"})
print(format_egress_map([refund_usd]))

payments_refund_usd  (POST v1/refunds)
  visible to the model (3):
    + charge
    + amount
    + reason
  withheld (1):
    - currency  [pinned] = 'usd'
  pinned (1):
    = currency  'usd'

Commit that map and a change to it is a diff in review: a new tool, a widened field, a dropped pin. The audit artifact has the CI check.

Act for one customer

A rule like “only this customer’s charges” needs to know whose account the call is for. That has to come from your app, not from the model, which can be talked into naming someone else. Mark the field FromContext() and pass its value with each call: a pin whose value arrives per call.

refund.py

from pydantic import model_validator

from charter import FromContext

OWNERS = {"ch_3MmlLr": "cus_42", "ch_8KpQ2z": "cus_7"}  # from your database


class CustomerRefund(CreateRefund):
    customer_id: Annotated[str, FromContext()]  # your app's, per call

    @model_validator(mode="after")
    def their_own(self) -> "CustomerRefund":
        if OWNERS.get(self.charge) != self.customer_id:
            raise ValueError("that charge belongs to another customer")
        return self


customer_refund = payments(
    name="customer_refund",
    description="Refund one of the customer's charges.",
    method="POST",
    url_template="v1/refunds",
    args_schema=CustomerRefund,
)

try:
    customer_refund.invoke(
        {"charge": "ch_8KpQ2z", "amount": 1500, "reason": "duplicate"},
        context={"customer_id": "cus_42"},
    )
except ToolValidationError as refused:
    print(refused)

print(format_egress_map([customer_refund]))

Validation error:
- **(input)**: Value error, that charge belongs to another customer
payments_customer_refund  (POST v1/refunds)
  visible to the model (4):
    + charge
    + amount
    + reason
    + currency
  withheld (1):
    - customer_id  [context] <- context['customer_id']

The model fills in the same four fields, and never customer_id. Asked for another customer’s charge, the call is refused before anything is sent, and so is a call your app made without saying whose it is. The map now says where that field comes from, which answers what a customer’s security team asks: can the agent choose whose data it touches? Per-call context has the rest.

Call a pack

A pack is the tools of one API, already declared the same way: a head start, not the limit. Configure the credential once and every tool in it is callable.

quickstart.py

import asyncio
import logging

from charter.packs import stripe

logging.basicConfig(format="%(message)s")
logging.getLogger("charter").setLevel(logging.INFO)

stripe.configure("sk_test_...")   # https://docs.stripe.com/keys

async def main():
    await stripe.customers_create.ainvoke({"email": "ada@example.com", "name": "Ada Lovelace"})

asyncio.run(main())

customers_create       POST v1/customers               200    782ms  ↑     33 B  ↓     661 B →     111 B  (83%)

Stripe takes an API key, so run this one first — a test key is enough. Look at the sizes on that second line. Stripe’s customer object comes back with twenty-three fields, and the model read six. You didn’t configure that. Every pack tool ships with a response handler tailored to its endpoint, there to keep your agent’s context window small — which is why Stripe’s twenty-three-field customer reached the model as six. Write your own with tool.derived(name=..., response_handler=...), or turn the trimming off with pass_through and get the response whole. The shape is yours either way: response handling, and seeing the wire for the headers and body.

Gmail, Calendar, Sheets, Docs, Drive and Forms need a Google OAuth client before their first call — Google issues no API key for them. Making one is ten minutes, once: Set up Google, a screenshot per screen. Every other pack’s credential, and the page that issues it, is on your own account.Gmail and the other OAuth packs take a credential provider instead of a key: gmail.configure(StaticTokenProvider(access_token)) is fine for a one-time script and wrong for a product, because the token expires in about an hour. See authorization servers for refresh against any OAuth 2.0 token endpoint, and getting the grant for where the refresh token comes from.

Hand it to a framework

Every pack exports TOOLS, and a list of your own declarations works the same way. An adapter turns either into what the framework expects.

from charter.adapters.openai import to_openai_tools
from charter.packs import gmail

tools = to_openai_tools(gmail.TOOLS)

from charter.adapters.langchain import to_langchain_tools
from charter.packs import gmail

tools = to_langchain_tools(gmail.TOOLS)

uvx --from 'charter-ai[mcp]' charter-mcp --pack gmail

The OpenAI format needs nothing beyond the core. LangChain needs pip install 'charter-ai[langchain]'. Client configuration for the MCP server is on its page, and the other two on adapters.

Get started

Declaring a tool

The boundary

Authentication

Using your tools

Optimization

Running it

Guarantees

Declare a tool

Break a rule

Pin a value, and see what the model sees

Act for one customer

Call a pack

Hand it to a framework

Next steps

The wire contract

Authentication

​Declare a tool

​Break a rule

​Pin a value, and see what the model sees

​Act for one customer

​Call a pack

​Hand it to a framework

​Next steps

The wire contract

Authentication

Declare a tool

Break a rule

Pin a value, and see what the model sees

Act for one customer

Call a pack

Hand it to a framework

Next steps