Agents

An agent is an AI worker with a specific job. It has:

• a system message: its role and instructions;
• an LLM configuration: the model that powers it;
• optional functions: the tools it can call.

You can chat with an agent directly, put it on a team, drop it into a workflow, or let other agents call it as a sub-agent.

Where agents live

Open Build → Agents. The left pane is the Agent Library, a folder tree of every agent in your current project.

• Add agent (the + button) starts a new agent.
• Add folder creates a folder.
• Drag an agent onto a folder to move it there.
• Select an agent to open it in the right pane.

When nothing is selected, the right pane may show a builder chat: describe the agent you want and the platform's builder agent creates it for you.

Agents belong to a project. You only see the agents in the project you're working in, and agent names must be unique within that project. Switching project switches the library. See Organisations and Projects.

What makes a good agent

Build specialists, not generalists:

Instead of...	Build this
"General purpose assistant"	Research Analyst: finds and summarises information from web sources
"Do anything agent"	Code Reviewer: checks code for bugs, security issues and style
	Report Writer: turns research notes into a structured report

A focused system message gives the model clear guardrails. It also helps teams route work to the right member.

Creating an agent

1. Click + in the Agent Library.
2. Enter an Agent Name and a System Message.
3. Choose an LLM Configuration. This is required.
4. Optionally add a Greeting, Opening suggestions, Tags and a Default Role, and set Approval Override, Execution Environment and Memory Policy.
5. Click Assign Functions to give it tools. Tick Streaming or Memory if you want them.
6. Click Create Agent.

The new agent opens on its Overview tab. Every field is described in Agent Settings.

The agent page

The header shows the agent's name, status chips (for example Active, a risk level, Unreviewed or Platform) and a reach ribbon summarising what it can touch. Click the reach ribbon to open Topology. The header also holds the killswitch and Open in Chat.

Tab	Use it to
Overview	See the system prompt, model, tools, approval posture, readiness, 30-day activity, tests and where the agent is used.
Configure	Edit the agent's settings, profile picture and functions.
Topology	See every tool, integration, trust boundary and external host the agent can reach, plus any findings.
Tests	Define and run evaluation test cases. See Testing Agents and Teams.
Sub-agents	Choose which other agents this agent may call or hand a chat to.
Repositories	Tell the agent which GitHub repositories it works on.
Memory	Attach knowledge bases and manage long-term memories. See Memory.
Observability	Usage, cost, completion rate, errors and a per-session audit trail. See Observability.
Risk	Record the agent's risk classification and review it.
Controls	Governance control evidence. See Governance.
Identity	Manage the agent's own platform identity and which credentials its tools use.
History	Review every configuration change and restore an earlier revision.

Writing the system message

The system message has the most influence on how well an agent performs. Include:

1. Role: who the agent is and what it's expert in.
2. Scope: what it should do, and what it should not.
3. Output format: Markdown, JSON, bullet points, headings, and so on.
4. Constraints: tone, safety and content rules.
5. Tool guidance: when to use its tools, and when to rely on its own knowledge.

You are a competitive intelligence analyst. You research companies and
markets using your web search tools.

When given a company or market:
1. Search for recent news, financial results and product announcements
2. Identify the main competitors and how they are positioned
3. Summarise your findings with a source URL for every claim

Use Markdown headings. If data isn't available, say so; never speculate.

If an agent isn't performing well, tighten the system message first: be more specific, give an example of good output, and rule out what isn't working.

Greeting and Opening suggestions shape how a one-to-one chat starts. The greeting is the agent's first message. The suggestions appear as one-tap chips until the user types their own message.

Tools

An agent with no functions can only reason and write. Functions let it search, call APIs, run code and act in other systems. See Adding Tools to Agents and Functions.

The platform also gives agents some built-in tools:

• Memory tools, when Memory is ticked.
• Readers for large tool results.
• Optional conversation search, event waiting and hand-off tools.

How approval is decided

When an agent calls a tool, FYAI decides whether a person must approve the call first.

1. Pins win. A pin is an Always require or Never require setting. FYAI checks for pins in this order and the first one it finds applies:

   1. the team the agent is running in;
   2. the agent's Approval Override;
   3. the function's own approval setting.

2. Critical risk can't be pinned off. If the call is critical risk, a Never require pin is ignored and approval is still required, unless the applicable risk appetite is Bypass all.

3. Otherwise the risk appetite decides. FYAI compares the risk level of the function (or of the agent, if the function has none) with the risk-appetite tier. The tier can be set for the organisation, a project, an individual user or a workflow; the most specific one applies, and a user's own tier can only be stricter than the project's unless an admin allows otherwise. The default is Balanced:

   Tier	Approval needed for
   Cautious	medium risk and above
   Balanced (default)	high and critical risk
   Critical only	critical risk only
   Bypass all	nothing, not even critical risk

   A tool with no risk classification requires approval under every tier except Bypass all.

The agent's Overview tab shows its effective approval posture and why. For approval steps inside workflows, see Using Approval Gates.

note

Runs started through the API (/agents/{id}/run and /run-async) are unattended, so they're treated as Never require. Critical-risk calls still require approval.

Sub-agents and hand-offs

An agent can delegate work to another agent in the same project, but only if you've granted it permission. On the orchestrating agent's Sub-agents tab, pick an agent under Agent and click Grant. Grants are one-way: A may call B doesn't mean B may call A. Changing grants requires the project Editor role.

With a grant in place, the agent can:

• Invoke a sub-agent through the invoke_sub_agent function. The sub-agent runs in its own linked session and its answer comes back as the tool result. Chains can go up to 5 agents deep, and cycles are refused. See Built-in Tools.
• Hand the conversation over with the hand_off_to_agent built-in. This works in one-to-one chats. The user continues with the specialist in a new session.

Identity

Each agent can have its own platform identity: a service account created automatically when the agent is first saved, or on its first chat. When the agent's tools call integrations and platform APIs, they act as the agent rather than as you. The Identity tab shows the identity's status, credentials metadata and health checks.

On the same tab, Tool Identity lets you redirect which integration a tool uses for this agent only. For example, an approval in GitHub must come from a different account to the one that opened the pull request. An override changes which credential is used. It never widens what the agent can reach.

Repositories

On the Repositories tab, choose the GitHub repositories the agent works on. The agent is told about them, with their default branches, at the start of every chat, so you don't have to name the repository each time. This is context, and for calls made through the FYAI GitHub App it also limits the agent to these repositories. A GitHub tool that uses a stored credential is limited only by that credential. See GitHub repositories. Connect GitHub under Settings → Repositories first.

Killswitch

The Active / Killed switch in the header stops an agent immediately. Until you reactivate it, a killed agent can't be run anywhere on the platform (new chats, API runs and workflow nodes that use it are refused), and its configuration is read-only.

When you kill an agent you can also tick Also terminate active chat sessions for this agent. Killing or reactivating an agent requires the project Editor role.

History and rollback

Every create, update, rollback and killswitch change is recorded on the History tab, with who made it and which fields changed. Expand a revision to compare it with the previous one, or click Restore this revision.

A restore is recorded as a new revision. It never restores credentials or the killswitch state.

Platform-managed agents and templates

Your library can include agents provided by the platform. These are marked Platform and Managed by platform — read only.

• Starting a chat with one gives your project its own managed copy.
• A project created with Include platform-managed resources turned off doesn't show them.
• You can also add agents from templates in the Marketplace. See Templates.

Running an agent

How	When to use it
Open in Chat	Starts a new one-to-one conversation in the docked chat. See Chatting with Agents.
Team or workflow	Add the agent to a team, or use an Agent node in a workflow.
API: POST /agents/{id}/run	One-shot run that waits for the reply.
API: POST /agents/{id}/run-async	Background run. Poll GET /agents/run-async/{execution_id} until its status is completed or error. Use this for anything longer than about a minute.

API runs take a message and, optionally, prior_messages (earlier turns) and llm_config_override_id. They return the output, token usage and cost. A killed agent returns HTTP 423. See the Platform API; the Platform MCP server exposes the same runs as run_agent, run_agent_async and get_agent_run_status.

Copying an agent

Click Copy Agent, enter a New Agent Name and click Copy. The copy has the same system message, model, tags, default role, approval override, execution environment, Silent / Streaming / Memory settings and assigned functions.

The copy does not carry over the Greeting, Opening suggestions, Memory Policy, profile picture, sub-agent grants, repositories, tool identity overrides, risk classification or test cases. Set those again on the new agent.

Related

• Agent Settings: every field
• Built-in Tools
• Teams
• Functions
• Models
• Observability
• Testing Agents and Teams