Publish and call an agent

Every agent is published with an Ontology binding and an agent API name. Once published, the agent's function is callable from both Workshop and the Ontology SDK (OSDK) with no additional configuration.

Ontology binding

An Ontology binding associates your agent with a specific Ontology. The binding determines which Ontology resources the agent can access through its scoped permissions.

To ensure every agent is bound to an Ontology, the agent configuration page includes a required Ontology selector. Select the Ontology your agent will read from and write to before you publish.

Agent API name

Each agent is published with an agent API name that identifies the agent's function when it is called from Workshop or OSDK. The agent API name is derived from the repository name, and you can edit it in the Agent API name field on the agent configuration page.

Publish an agent

When you publish an agent, Foundry registers it with its Ontology binding and agent API name and exposes it as a function. After publishing, no further configuration is required to call the agent.

Trigger an agent

An agent function runs asynchronously and is not subject to the synchronous function execution limit of five minutes.

From Automate (recommended)

We recommend triggering an agent from Automate. Configure an automation with a function effect that points at your agent's function. The agent runs as the user that triggered the automation, or as the service user backing the automation.

From Workshop, Ontology SDK, or Ontology actions

You can also invoke an agent function wherever asynchronous functions are callable, including Workshop, the Ontology SDK, and Ontology actions.

Note the following when calling an agent function directly:

• The function returns no value: An agent function returns Void, so it cannot be called as a query function. To invoke it from Workshop, the Ontology SDK, or Ontology actions, call it as a function effect or wrap it in a TypeScript Ontology edit function that invokes the agent.
• Consume results through the Ontology: Because the function does not return a value, have your agent write its transcripts or results to Ontology objects, then read those objects to consume the output. This pattern also applies when grading agent output with AIP Evals.
• Streaming and batch invocation are not supported.

Pass arguments to an agent

Agents accept arguments defined in the AgentArguments schema in agent/index.ts.

When you trigger an agent, provide a JSON object with keys that match your AgentArguments schema. For Ontology objects, pass primary key values rather than whole objects, and re-fetch the objects inside your agent through the Ontology SDK or Ontology MCP.

To run an agent locally during development, provide arguments through the template's start command using --json-args for inline JSON or --json-args-file for a JSON file:

Copied!
1
npm start -- --json-args '{"additionalAgentContext": "some context"}'

Next steps

• Build and publish your first agent in Foundry.