Docs / Reference

FAQ

The questions people actually ask in the first month, with short answers and where to read more.

Building

Can a function contain AI? Yes. A function is a fixed list of steps, and a step can call a model as well as call an operation or work on data it already has. What makes it a function is that the steps are fixed and the same input gives the same answer, not that no model is involved. See Build a function.

How do I make sure the agent actually uses a tool? Put it in the script, not the prompt. A stage says what it is allowed to use and what it must have collected before it can move on, so the invoice agent cannot leave stage two without a comparison result. Asking nicely in the system prompt is a suggestion; a stage condition is not. See Write a script.

Do I have to write a script, or can I just prompt it? For a question-and-answer agent, prompt it. For a job with steps, write a script, because otherwise nothing stops it skipping to the end and nothing tells you which part went wrong. See Write a script.

Where do I change an agent that already exists? The Agent Builder, docked on the left of every agent tab. Describe the change in words on the tab the problem lives on. Orca is for provisioning something you do not have yet, not for editing. See Diagnose and improve an agent.

My agent is right most of the time and wrong sometimes. Something is being left to the model that should not be. In order: the script is doing too little, it cannot reach what it needs, an instruction can be read two ways, or nothing is judging the output. See Diagnose and improve an agent.

Reaching other systems

Do I have to write operations by hand? No. Press Discover on the connection's Overview tab. It looks in the standard places a system publishes its API description, or reads one documentation page you paste, or looks at a database's tables and what your login can do. Nothing switches itself on. See Connect a system.

What exactly does an agent get: the connection or the operations? Operations. Never the connection. The complete list of what your agents can do to your finance system is the list of operations you enabled, and you can read it. See Connect a system.

It works when I test the connection and the agent still cannot call it. Three separate things have to be true: it is enabled on the connection, it has been given to that agent and applied, and if it is a write, somebody has approved it. Check them in that order. See Connect a system.

Can an agent send an email on its own? No. Anything that changes an outside system is a write, and a write waits for a person to approve it. An agent can never approve a write, its own or another agent's, unless an org policy in Settings → Governance allows it, and then the record names the policy. See Making it run, and approving what it does.

How do I cut off access immediately? Revoke the operation on the connection. That is checked every time it runs, including in a conversation already under way. Changes on the agent only reach people on their next conversation. See What saving actually does.

Running and approving

Why did my run finish and change nothing? The most common false alarm there is. The agent reached its write, recorded exactly what it would send, and the run finished normally. The change is sitting on an approval link waiting for a person. Find the approval. See Making it run, and approving what it does.

Did it even run? Observability → Resources, or ask the Observability Guide docked on the left. No run recorded means nothing started it, so look at the trigger rather than the agent. See Check what happened.

My run stopped part way. Can I resume it? No. Resuming would mean deciding on its own that a half-finished set of changes to your systems should be completed. The record shows how far it got, the same run cannot execute twice, and re-running is your decision. A re-run starts from the beginning. See Limits and run behaviour.

Why did it stop at all? A run gets about a minute when somebody is waiting for the answer and about five minutes when nobody is, and it can reach outside about 100 times. The ceilings exist because an agent with a bad instruction does not fail, it keeps going. See Limits and run behaviour.

It sticks on the same stage every time. Read the report the agent was given. It names the condition that did not hold. Usually the condition is worded vaguely rather than the agent being poor. See Write a script.

Testing

How much does a passing test prove? That every pinned criterion passed, every time it ran. Each criterion runs several times and at default settings a judged one has to pass all five. A better average never overrides a single failure. See Test an agent's behaviour.

Will a test really call my finance system? Yes. Tools execute for real during a test. Point the connection at a sandbox if the side effects matter. See Test an agent's behaviour.

Can I fix a criterion I worded badly? No. Pinned criteria cannot be edited or deleted. Retire it with a reason and pin a replacement. Run new ones unpinned first, which is what the unpinned run is for. See Test an agent's behaviour.

Can I test conversations, not just single answers? Yes. A stand-in user driven by a persona and a goal keeps the conversation going until the goal is reached, it gets stuck, or a turn limit stops it, and the whole conversation is scored. See Test an agent's behaviour.

Sharing and access

What am I giving somebody when I publish an agent? The bundle. Publishing the invoice agent gives them read access to your finance system through those four operations, and the ability to register supplier queries for approval. Not the finance system, and nothing else on it. See Publish and share an agent.

Do I need to be an admin to use agents from Claude? No. If an agent is published to you, you can add the server in Claude or Claude Code and call it. There is a separate admin surface for authoring, which is a different thing. See Use your agents from Claude.

I published it and they cannot see it. Check the agent's own status and who it is published to separately, then check the environment. An agent published in Test does not appear in Production. See Publish and share an agent.

My call from Claude timed out. Did the agent fail? No. A call cannot be cancelled once it has started, so the agent carried on and finished in Mindset. Read the run in Observability before you call it again. See Use your agents from Claude.

Can somebody build their own agent? Yes, from the Hub, if an admin has turned personal agents on in Settings → Governance. They are owned by the member, never published to anyone else, and cannot hold resources, so a personal agent cannot reach your finance system. See Publish and share an agent.

Cost and change

What is this costing us? The Costs workspace: total spend, metered calls, average cost per call, average input tokens per call, tokens in with the percentage from cache, tokens out. Broken down by agent, function, model, provider or user. See See and control what it costs.

How do I make it cheaper without making it worse? Re-run the behaviour tests with the model swapped and take the cheapest model that still passes every criterion. That comparison run is marked experimental and cannot itself promote anything, so changing the model is still a separate step. See See and control what it costs.

I saved and nothing happened. Three kinds of save. System prompt, script and most settings are immediate. The Resources tab is saved to a draft and needs Apply & make live. Functions, scripts and widgets become a version that you then publish. Also, anyone mid-conversation keeps what they started with. See What saving actually does.

How do I undo something? Re-activate an earlier version on the Versions tab. Functions, scripts, widgets, an agent's resource assignments and its prompt content all keep versions. The agent's own record does not: it has a status of draft, published or archived. Connections do not either: an operation is enabled or it is not. See Change something that's already live.

Who owns this agent? Whoever the description says. There is no owner field, so ownership is a convention: put the owner and a backup in the agent's description in the same format every time. See Keep track of what you have.