Agents, knowledge and connections

Agents, knowledge bases and connections are definitions like tables and flows. Keep them in your repository, review changes in pull requests, and deploy the same agent to staging and production. For what each one does, see Agents, Knowledge bases and Connections.

from pawabase_iac import Agent, Connection, KnowledgeBase, tools

Agent

support = Agent(
    "support",
    model="chat",
    policy="authenticated",
    description="Answers customers about their orders",
    instructions="You help customers with their orders. Answer from the help articles. Be brief.",
    tools=[
        tools.table(orders, ["list", "get"]),
        tools.flow(request_refund, description="When a customer asks for a refund"),
        tools.web_fetch(allow_hosts=["docs.example.com"]),
    ],
    knowledge=[help_articles],
    limits={"max_steps": 8, "max_cost": 0.5},
)

Argument	Meaning	Default
`name`	Letters, digits, dashes and underscores	required
`model`	The name of a chat model of the environment	required
`instructions`	What it should do, up to 50,000 characters	empty
`description`	A note for your team and for agents that hand over to it	empty
`tools`	A list built with `tools.…` helpers. At most 50.	none
`knowledge`	Knowledge bases it may search (definitions or names)	none
`policy`	Who may run it: a policy or a policy name	`"service"` (servers only)
`run_as`	`"caller"` holds its tools to the asking person’s access; `"service"` runs with the agent’s own authority	`"caller"`
`approval_policy`	Who may approve its waiting calls besides whoever started the run	none
`limits`	A dictionary of the limits below	defaults apply
`params`	Model settings such as `temperature`	none
`enabled`	Switch it off without deleting	`True`

Limits

Key	Meaning	Default	Highest
`max_steps`	Model turns and tool calls in one run (whole number above 0)	12	50
`max_seconds`	Time in seconds (whole number above 0)	120	900
`max_tokens`	Tokens (whole number above 0)	none
`max_cost`	Dollars (above 0)	none
`guard_untrusted`	After reading outside content, changes wait for a person	`True`

validate rejects an unknown limit name or a value of the wrong kind. See Approvals and limits.

Tools

Every helper returns one entry for Agent(tools=[...]). Tables, flows, connections and other agents can be passed as the definitions themselves or by name. Anything that changes data waits for a person unless approval="auto" says otherwise; approval="ask" asks every time.

Helper	What it gives the agent
`tools.table(table, actions, approval=, policy=, description=)`	A table. `actions` is any of `list`, `get`, `create`, `update`, `delete`. Default `("list", "get")`.
`tools.flow(flow, description=, name=, input=, writes=True, untrusted=False, approval=, policy=)`	A flow. `writes=True` marks it as changing things; `untrusted=True` marks what it returns as outside content. `input` fixes some inputs.
`tools.web_fetch(allow_hosts=, approval=)`	Open and read a page. `allow_hosts` limits it to those sites. Private addresses are always refused.
`tools.web_search(connection=None, provider=None, approval=)`	Search the web. `provider` is `"duckduckgo"` or `"model"` (the model’s own search), or pass a search `Connection`.
`tools.notion(connection, actions=("search", "read"), approval=)`	Notion. `actions`: `search`, `read`, `create`, `append`.
`tools.mcp(connection, only=None, approval=)`	An MCP app. `only` lists the tool names it may use.
`tools.agent(agent, description=, name=, writes=True, approval=)`	Hand a job to another agent.
`tools.code()`	Run code in the model provider’s sandbox (Anthropic and Gemini models).
`tools.image(provider, model, description=)`	Make images.
`tools.x_search(model, handles=)`	Search X with an xAI model. Up to 20 `handles`.
`tools.tool_search()`	Hide big apps’ tools until the agent looks for them.

tools.table(orders, ["list", "get", "update"], approval="ask")
tools.mcp(github, only=["search_issues", "get_issue"])
tools.notion(wiki, actions=["search", "read", "create"])

Connection

A connection holds the address and the name of a secret that holds the key, never the key itself. Set the secret in Studio or with the management client, then deploy.

Connection.notion("wiki", secret="NOTION_KEY")
Connection.mcp("github", "https://api.githubcopilot.com/mcp/", secret="GITHUB_TOKEN")
Connection.mcp("jira", "https://mcp.atlassian.com/v1/mcp", secret="JIRA_TOKEN", auth="basic", username="you@example.com")
Connection.mcp("context7", "https://mcp.context7.com/mcp", secret="CONTEXT7_KEY", auth="header", header="CONTEXT7_API_KEY")
Connection.web_search("exa", provider="exa", secret="EXA_KEY")

Constructor	Arguments
`Connection.mcp(name, url, secret="", auth=None, header=None, scheme=None, username=None)`	`url` is the app’s MCP address. `auth` is `"bearer"` (the default way: `Authorization: Bearer <key>`), `"header"` (send the key in the header named by `header`) or `"basic"` (with `username`). `scheme` replaces `Bearer` with another word, for example `Sentry-Bearer`.
`Connection.notion(name, secret)`	A Notion integration secret
`Connection.web_search(name, provider, secret="")`	`provider` is `"tavily"`, `"exa"` or `"duckduckgo"`

KnowledgeBase

help_articles = KnowledgeBase("help", embedding_model="embed", policy="authenticated")

Argument	Meaning	Default
`name`	The base’s name	required
`embedding_model`	An embedding model of the environment. It can’t change once documents have been read with it.
`description`	A note	empty
`policy`	Who may search it	`"service"`
`chunk_size`	Characters per passage	1200
`chunk_overlap`	Characters shared between neighbouring passages	150

The documents are data, not definitions: add them from Studio or the SDK (ai.knowledge.add_document). See Add documents and search.

Checks before you deploy

pawabase validate checks, offline: that an agent’s model, tools, knowledge bases and policies exist; that limits are valid; that connections referenced by tools exist and have a kind that suits the tool; and that a tool’s table actions are real. Names that don’t exist are reported with the place they were used.

Deploying

Promote and deploy handle these like other definitions: the connection’s secret and the model must exist in the target environment first. A knowledge base arrives empty. See Plan and deploy.

Fields

Vector fields for search by meaning.

Policies

Who may run an agent.

Overview

Infrastructure as code

Define your backend

Logic and events

Files and mail

Ship it

Reference

SDK clients

Agents, knowledge and connections

Agent

Limits

Tools

Connection

KnowledgeBase

Checks before you deploy

Deploying

Fields

Policies

​Agent

​Limits

​Tools

​Connection

​KnowledgeBase

​Checks before you deploy

​Deploying

Fields

Policies

Agent

Limits

Tools

Connection

KnowledgeBase

Checks before you deploy

Deploying