Create and run an agent
An agent is a language model with a system prompt, a set of tools it may call, and optionally other agents it may delegate to. You talk to it, and it decides at each step whether to call a tool, hand part of the job to a sub-agent, or answer.
This guide takes you from an empty project to a deployed agent that you have tested in Tiet · Studio and called from the API. The worked example copies a real catalog agent, changes it, and deploys it.
Agent, workflow or agent graph
| You need | Use | Why |
|---|---|---|
| A conversation or an open-ended task where the model decides which tools to use | Agent (this page) | One prompt, one model, tools chosen at run time. Streams a chat reply. |
| The same fixed steps every time, wired by you, with no model deciding the order | Workflow in the Builder: Build any workflow | Deterministic nodes. A workflow can still contain an Agent Executor node when one step needs a model with tools. |
| Several model stages with different roles or models, pinned per stage, with a per-step record | Agent graph: Build an agent graph | Versioned graph of LLM nodes that runs as one execution. Slower and costlier than one agent. |
Start with a single agent. Move to a graph only when one prompt cannot hold the logic, or you need different models per stage.
How an agent answers
- Tools are actions the agent may call, such as
pubmed,medical-calculatorormemory. You assign them in the Design tab. A tool whose effect is above the run's autonomy ceiling is not offered to the model at all (see Agents and governance). - Sub-agents are other agents the agent may delegate to. Each one is exposed to the parent as a tool named
agent_<tool_name>, and runs with its own prompt and its own tools. - Models come from the registry in Tiet · Agentic → Agents → Models. The Design tab's Model section picks one. Different models can be routed to different phases (see below).
- Agent type is set when you create the agent: Conversational (multi-turn chat with memory), Task (single-shot task), Hybrid (chat plus task), or ReAct (reason, act, observe loop with tools). Use ReAct for an agent that relies on tools.
Where things are
Open Tiet · Agentic → Agents. The page has six tabs: Agents, Agent Graphs, Agent Catalog, Models, Tools and Skills. You see only the tabs you have permission for. At the top right are the Project selector, a Run in selector and New Agent. Run in chooses the environment that runs started from Studio execute in (the organization's default unless you pick another). An environment that allows drafts runs what the editor asks; any other runs only versions deployed to it. See Environments & Promotion.
The sidebar also has three siblings under Tiet · Agentic → Agents:
- Agent Workspace is where you chat with an agent or start a run.
- Monitor (Agent activity) lists recent executions across every agent and graph.
- Reviews (SEPL commit reviews) lists proposed agent changes waiting for a human decision, across all agents. See Agents and governance.
Create an agent
There are three ways to get an agent into your project.
Start from a catalog agent (recommended)
The Agent Catalog holds Tietai-managed base agents. About 110 are shipped, across coding and billing, clinical decision support, documentation, nursing, pharmacy, specialty care, operations and more. They are tested starting points with real prompts and tool lists.
- Select your Project at the top right. You need one; without it the copy cannot be created.
- Open the Agent Catalog tab, or click New Agent → Start from a Tietai base agent.
- Find the agent. The catalog search box says "Search agents by name, description, or tags…".
- Click Deploy to my org. Enter the Agent Name, then Deploy.
The result is an editable copy in your project, and the Designer opens on it. Despite the button label, the copy is not deployed yet: it is active, the version number is the base agent's, the tool assignments are copied, and the sub-agent references are copied by reference. The copy remembers which template it came from, and the History tab offers Review Changes when the template is later updated.
Start from scratch
- Click New Agent, then Start from scratch ("Configure a blank agent with your own settings.").
- Fill in the New Agent dialog:
| Field | Meaning | Example |
|---|---|---|
| Name | Required. | Discharge Summary Helper |
| Type | Conversational, Task, Hybrid or ReAct. Default Conversational. | ReAct |
| Description | Optional. | Drafts a discharge summary from a pasted note. |
| Project | Taken from the project selector. The dialog warns "No active project — select a project first." and Create stays disabled until there is one. | Demo Project |
- Click Create. The Designer opens. The system prompt, tools and model are set there.
Duplicate an existing agent
On an agent card, open the actions menu and choose Duplicate. The copy is named <name> (Copy) and includes tools, skills and policies. It is created inactive on purpose and is never copied as deployed or published to Inference. If some linked items fail to copy, you see "… was created, but N linked configuration item(s) could not be copied. Review the duplicate before use." The Designer has no switch to make an inactive agent active again, so for a copy you intend to run, prefer the catalog route above.
Move agents to another project
On an agent card, the actions menu has Move to project…. Tick the checkboxes on several cards (shift-click selects a range) and use the selection bar to move them together. Only the project changes. Catalog base agents and agents of other organizations cannot be moved, and you need permission to update agents. The destination must be a project of the same organization.
The Agent Designer
Click an agent to open the Designer. The tabs are:
| Tab | What it contains |
|---|---|
| Design | The configuration: Identity, Prompt, Variables, Tools, Skills, Execution, Sub-Agents, Memory, Model. Save and Deploy buttons on the right. |
| Policies | Governance rules for this agent. New Policy offers five types: IntentGuard (block user intents that match a trigger), Playbook (inject step-by-step instructions into the system prompt), ToolGuide (append guidance to one tool's description), ToolApproval (pause for human approval before a tool is called, with a timeout in minutes) and OutputFormatter (formatting instructions for the final answer). Triggers: keyword, semantic, tool_name or always. Each policy has a priority and an enable switch. |
| Activity | Step-by-step record of one session: pick a session, see its steps and durations, and open it in the Trace Explorer. Empty until the agent has been run ("No sessions yet. Run the agent to see activity."). |
| Test | Chat with the deployed agent: Ask the Agent, Test Inputs (saved messages and files with an optional expected result) and Execution History. |
| Validate | Run Validation checks the configuration and lists issues by field, for example prompt_template: system prompt is required and model_config: model configuration is required. |
| History | The version list. New draft version starts a draft with optional change notes. |
| API | API keys for this agent, the invoke endpoint, the request schema and code samples in cURL, TypeScript, Python and Java. |
| Evolution | Self-evolving prompts (SEPL): mode, Run Evolution, parameters, pending reviews and history. See Agents and governance. |
The top bar shows the agent name, a version selector, a Deployed badge when it is live, and a Copilot button that opens an assistant panel beside the tabs. Users with the platform-manager role also see Publish to Catalog.
The Design tab sections
| Section | Fields and controls |
|---|---|
| Identity | Name, Description, Version, Tags (type a tag and press Enter), Agent Type. |
| Prompt | System Prompt: sent to the model at the start of every conversation. Write {{name}} for a value you fill in per call (the invoke API calls these variables). With Model Routing on, this becomes four per-phase prompts (Planning, Tool Call, Reasoner, Synthesis) plus a default prompt for empty phases. |
| Variables | Declares what a caller supplies for each {{name}} in the prompt: name, type (string, text, number or boolean), required and an example. Add variable, or Declare N from the prompt to add the placeholders the prompt uses and you have not declared. At most 50. Declarations are versioned with the agent, and variable presets are checked against them (a missing required value, a non-number or a string over 1000 characters is refused; declare long values as text). The invoke endpoint itself does not enforce them. |
| Tools | Every tool available to your organization, grouped by category. Click one to assign or remove it. Assigning a tool that can act, rather than only read, opens a permission-review dialog first. |
| Skills | Capability packs the model loads on demand. The auto switch injects a skill's instructions before the first model round. |
| Execution | Default Execution Mode (Fast, Balanced, Accurate), Auto Variable Tracking, Auto Planning, Model Routing (one model per phase), Shortlister (ranks tools by relevance; needs Qdrant) and Code-Act Mode. |
| Sub-Agents | Add Sub-Agent. For each: Agent ID, Tool Name, Invocation (sequential, parallel, fire-and-forget) and Description ("When to delegate to this agent"). |
| Memory | Enable memory, then Memory Type (episodic, semantic, procedural, working), Memory Backend, and a Retrieval Strategy for the Memora backend. |
| Model | Model picker (with "key set" or "no key" for the selected model), Temperature, Max Tokens (256 to 128000), Enable streaming, and Manage model credentials. |
The right-hand column has Save Changes, Deploy, a Publish to Inference checkbox (makes the agent a template on the Medical Inference page) and a Status panel (Active, Deployed, Published, Up to date).
The Invocation value is saved with each sub-agent reference. In the chat and invoke path, every sub-agent is registered as a callable tool named agent_<tool_name> and the model decides when to call it; nothing in that path branches on sequential, parallel or fire-and-forget. Do not rely on the mode to change how delegation runs.
A delegation stops with an error the parent sees as a failed tool call after 20 model calls or 10 tool-calling turns by default. A conversation is also limited to 30 delegations per hour per server process. If max_sub_agent_depth is not set, the depth limit is 2.
Versions: draft, deploy, frozen
- An agent that is not deployed is edited in place. Save Changes asks for optional change notes and bumps the patch version (for example
1.1.0to1.1.1). - Deploy records the current configuration as a deployed version and marks the agent live. The Test tab, Agent Workspace and the invoke API run what is deployed.
- A deployed version is frozen. Saving a change to it is refused with HTTP 409 and the code
AGENT_DEPLOYED_IMMUTABLE, and the Designer says "This version is deployed and immutable. Create a new version to change it." Name, description, tags, project and the Inference setting stay editable in place. - To change a deployed agent, click New version (or New draft version in History). You edit the draft; the running agent does not change. Save draft, then Deploy vX.Y.Z. Discard draft throws it away.
- Every version stays readable. To roll back, start a draft from an older version ("New version from this") and deploy it.
- Tool and skill assignments are not part of a version. They are live-editable and are not frozen with it. Declared Variables are part of the version.
The Designer has no Undeploy button, although the API has POST /api/agents/{id}/undeploy.
Worked example: copy, adjust, test, deploy, call
You will copy the Laboratory Results Interpreter catalog agent, add a rule, and call it. Its catalog definition: type react, model gemini-2.5-pro (provider google), temperature 30, max tokens 8192, compliance_level: hipaa, tools medical-calculator, pubmed, memory and ui, no sub-agents. Its prompt interprets lab results against reference ranges, screens for critical values and pre-analytic problems such as hemolysis, and writes Markdown sections such as ## Result Summary and ## Critical Value Screen.
Use synthetic data only.
1. Copy it
- Select a project.
- Tiet · Agentic → Agents → Agent Catalog. Search for "Laboratory".
- On Laboratory Results Interpreter, click Deploy to my org, set Agent Name to
Lab Interpreter (Demo Hospital)and click Deploy.
You land in the Designer. The top bar shows v1.1.0 and no Deployed badge. In Tools (4) the four tools are ticked.
2. Adjust it
- Design → Identity: change Description to
Interprets lab results for Demo Hospital clinicians. - Policies → New Policy → Playbook. Name it
Units on every value, set the trigger to always, and in Instructions (Markdown) write1. Print every value with the unit exactly as reported by the source laboratory.Click Create Policy. - Design → Save Changes, add the note
Demo Hospital description, and confirm. The version becomes1.1.1.
A Playbook policy injects your instructions into the system prompt without you editing the catalog prompt, which is long and carries its own output contract. Policies are not part of a version, so you can change them after deploying.
3. Validate and deploy
- Validate → Run Validation. You should see Agent is valid. If not, each issue names the field.
- Design → Deploy. The Deployed badge appears and the Test tab becomes usable.
4. Test it
-
Open the Test tab. Before you deploy, it shows "Agent not deployed. Deploy the agent from the Design tab to start testing."
-
In Ask the Agent, send:
Test Patient A, 54 years old. Potassium 6.4 mmol/L, creatinine 2.1 mg/dL.
The specimen is marked hemolyzed. Interpret these results. -
You should see the reply stream in, with the tool calls the agent made. Check that it screens for a critical value, raises the hemolysis as a possible pre-analytic cause, and prints the units.
-
Open Activity to see the same session step by step, and Test → Execution History for the run record.
To keep a message for later, use Test Inputs: enter an Input name, the Message, optional attachments, and an optional Expected result.
5. Chat with it in Agent Workspace
- Tiet · Agentic → Agents → Agent Workspace. The launcher lists your active agents and graphs as cards, sorted by name. A conversational, hybrid or ReAct agent is in Ask mode; a Task agent is a Tool.
- Open your agent's card and click Start conversation. Type in "Ask a follow-up, paste a link, or attach a file…". The screen carries the note "Clinical decision support only".
6. Call it from the API
-
Open the API tab and click Generate Key. Fill in Name, optional Description, Expires in (30 days, 90 days, 1 year or Never), Rate limit (requests per minute, 0 is unlimited) and an optional IP whitelist (one per line). The key is scoped to this agent (
agent:<agent id>:execute). -
Copy the token immediately: "Store this token — it won't be shown again".
-
Call the endpoint. Through the gateway the path is
/api/v1/hydra-platform/v1/agents/{id}/invoke:curl -X POST https://api.tiet.ai/api/v1/hydra-platform/v1/agents/AGENT_ID/invoke \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Test Patient A. Potassium 6.4 mmol/L, hemolyzed specimen. Interpret.",
"stream": false
}'
The API tab fills in AGENT_ID and your own {{variable}} names for you.
| Request field | Type | Notes |
|---|---|---|
message | string | Required unless you send attachments. |
variables | object of strings | Values for the {{name}} placeholders in the prompt. |
stream | boolean | true returns Server-Sent Events (data: {...} frames). The API tab's streaming sample adds Accept: text/event-stream. |
history | array of {role, content} | Earlier turns, if you keep the conversation yourself. |
attachments | array | Files for the model; sent instead of, or with, a message. |
With stream: false the reply is one JSON object. It includes content (the answer), input_tokens and output_tokens, and when tools ran, tool_calls and tool_trace. With stream: true the stream ends with a frame that has "done": "true", the token counts and final_content; an error ends it with {"type": "error", ...}.
7. Change it after deployment
- Open the agent and the Design tab. A banner says the running configuration cannot be edited in place.
- Click New version, edit the draft, Save draft, then Deploy v1.1.2.
- History now lists the earlier versions and the new one. The older deployed versions are still readable.
Monitor what agents do
Tiet · Agentic → Agents → Monitor ("Agent activity: recent executions across every agent and subagent graph") shows tiles for Runs, Success rate, Failed, Running now, Avg duration and Cost, filters for type, status, period, agent and name, and an Executions table with agent, type, status, started, duration, tokens, cost, triggered by, and a link to the trace. The invoke API call from step 6 appears here.
Limits
- The Test tab only runs a deployed agent.
- Tool and skill assignments are live and are not versioned.
- Sub-agent Invocation modes are stored, not applied in the chat path (see the note above).
- Model fallback, durable runs and loop protection belong to agent graph nodes, not to a single agent. See Agents and governance.
- The catalog's base agents are read-only to you. Only a platform manager can edit one, and edits there affect every organization.
Troubleshooting
| You see | Cause and fix |
|---|---|
| Create is disabled and the dialog says "No active project — select a project first." | Choose a project in the project selector at the top right. |
| New Agent button missing | You lack the create-agent permission. Ask an organization administrator. |
| Test tab: "Agent not deployed" | Click Deploy in the Design tab (save first; Deploy is disabled while there are unsaved changes). |
"This version is deployed and immutable. Create a new version to change it." (409 AGENT_DEPLOYED_IMMUTABLE) | Click New version, edit the draft, deploy it. |
Validation: system prompt is required or model configuration is required | Fill the Prompt section, or pick a model in the Model section. |
| Model section says "No models configured." or "no key" | Register the model and its key under Tiet · Agentic → Agents → Models. |
Invoke returns 400 message or attachments required | The body has no message. |
Invoke returns 403 Access denied or Agent is not active | The key belongs to another organization, or the agent is inactive (for example, an untouched duplicate). |
Invoke returns 404 Agent not found | Wrong agent ID in the URL. |
| A delegation fails with "sub-agent delegation limit reached" | The conversation used its 30 delegations for the hour. Start a new conversation or reduce delegation. |
Related
Something unclear? Send documentation feedback by email.