Kern

API Usage

Running your Agent / Team / Workflow with the AgentOS API

The AgentOS API provides endpoints:

  • Run an Agent: POST /agents/{agent_id}/runs (See the API reference)
  • Run a Team: POST /teams/{team_id}/runs (See the API reference)
  • Run a Workflow: POST /workflows/{workflow_id}/runs (See the API reference)

These endpoints support form-based input. Below is an example of how to run an agent with the API:

1curl --location 'http://localhost:7777/agents/kern-agent/runs' \
2    --header 'Content-Type: application/x-www-form-urlencoded' \
3    --data-urlencode 'message=Tell me about Kern.' \
4    --data-urlencode 'stream=True' \
5    --data-urlencode 'user_id=john@example.com' \
6    --data-urlencode 'session_id=session_123'

Passing parameters to your Agent / Team / Workflow

Agent, Team and Workflow run() and arun() endpoints support various runtime parameters. See the Agent run schema, Team run schema, Workflow run schema for more details.

It is a common pattern to want to pass session_state, dependencies, metadata, etc. to your Agent, Team or Workflow via the API.

To pass these parameters via the AgentOS API, you can simply specify them as form-based parameters.

Below is an example where dependencies are passed to the agent:

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.os import AgentOS
4
5# Setup the database
6db = PostgresDb(id="basic-db", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
7
8# Setup basic agents, teams and workflows
9story_writer = Agent(
10    id="story-writer-agent",
11    name="Story Writer Agent",
12    db=db,
13    markdown=True,
14    instructions="You are a story writer. You are asked to write a story about a robot. Always name the robot {robot_name}",
15)
16
17# Setup our AgentOS app
18agent_os = AgentOS(
19    description="Example AgentOS to show how to pass dependencies to an agent",
20    agents=[story_writer],
21)
22app = agent_os.get_app()
23
24
25if __name__ == "__main__":
26    agent_os.serve(app="dependencies_to_agent:app", reload=True)

Then to test it, you can run the following command:

1curl --location 'http://localhost:7777/agents/story-writer-agent/runs' \
2    --header 'Content-Type: application/x-www-form-urlencoded' \
3    --data-urlencode 'message=Write me a 5 line story.' \
4    --data-urlencode 'dependencies={"robot_name": "Anna"}'

Passing Output Schema

You can pass an output schema for a specific agent or team run by passing the output_schema parameter as a JSON schema string. By default, the schema is converted to a Pydantic model.

1curl --location 'http://localhost:7777/agents/story-writer-agent/runs' \
2    --header 'Content-Type: application/x-www-form-urlencoded' \
3    --data-urlencode 'message=Write a story' \
4    --data-urlencode 'output_schema={"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"}},"required":["title","content"]}'

To keep the output schema as a JSON dict instead of converting to a Pydantic model, set use_json_schema=true:

1curl --location 'http://localhost:7777/agents/story-writer-agent/runs' \
2    --header 'Content-Type: application/x-www-form-urlencoded' \
3    --data-urlencode 'message=Write a story' \
4    --data-urlencode 'output_schema={"type":"json_schema","json_schema":{"name":"StoryOutput","schema":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"}},"required":["title","content"],"additionalProperties":false}}}' \
5    --data-urlencode 'use_json_schema=true'

Cancelling a Run

You can cancel a running agent, team or workflow by using the appropriate endpoint.

For example, to cancel an agent run:

1curl --location 'http://localhost:7777/agents/story-writer-agent/runs/123/cancel'

See the specific API references for more details:

Developer Resources