Add subagent

[eznix86]

fix #58

example:

class PrimaryWithSubAgentsAgent implements Agent, HasSubAgents, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a primary agent that can delegate to subagents.';
    }

    public function subAgents(): array
    {
        return [new SubAgent];
    }
}

Edit: rename agents to subAgents

[pushpak1300]

Like the idea but don't you think the sub agent and Agent is kind of same thing, will it not work ?

Ideally agents() -> subAgents() and it should work without any problem ?

There could be interface called ActAsTool or any better naming which will take name and description and can be wrapped as a tool while sending to llm ?

[eznix86]

Yes, I was thinking of renaming it to subAgents() but the SubAgents are Agents themselves so I was back to using agents and having that one word function pretty nice to look. As for the rest currently, the sub agent is wrapped as a tool internally and sent to the LLM (should we make it explicitly with an interface? ActAsTool, I don’t think it is necessary, unless it will be exposed in another way) . That's the only way right now. Or we have to develop another way which is more complex with Agent to Agent Communication. But I think this is enough to for anyone to use. Here is the Syntax of a Sub Agent.

class FrontendEngineer implements SubAgent
{
    use Promptable;

    /**
     * Get the subagent name.
     */
    public function name(): string
    {
        return 'Frontend Engineer';
    }

    /**
     * Get the instructions that the subagent should follow.
     */
    public function instructions(): Stringable|string
    {
        return 'Build responsive, accessible, high-performance user interfaces using modern web technologies and best practices.';
    }

    /**
     * Get the description of the subagent's purpose.
     */
    public function description(): Stringable|string
    {
        return 'Builds and refines web UI from specs—creates responsive, accessible components and pages, integrates APIs, manages client-side state, handles loading/error states, and improves performance with clean, maintainable code.';
    }
}

// On Primary Agent

class Orchestrator implements Agent, HasSubAgents, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are an orchestrator that can delegate to other engineers.';
    }

    public function agents(): array
    {
        // every sub agents are turned into tools internally
        return [
              new FrontendEngineer,
              new BackendEngineer,
              new Devops,
        ];
    }
}

Since the subagent is an agent itself, it inherits all the Agent can do.

So you can do

#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Provider('anthropic')]
#[Temperature(0.7)]
#[Timeout(120)]
class BackendEngineer implements SubAgent
{
    use Promptable;
 
    // ...
}

#[Provider('gemini')]
#[Temperature(1)]
class BackendEngineer implements SubAgent
{
    use Promptable;
 
    // ...
}

#[Provider('openai')]
class Devops implements SubAgent
{
    use Promptable;
 
    // ...
}

[pushpak1300]

I know SubAgent technically extends Agent, but it doesn’t feel quite right to me. It’s still an Agent and can act independently, so calling it a SubAgent feels misleading.

Happy to hear Taylor’s thoughts on this.

[coreation]

@eznix86 Thanks for the effort, I know zero to none about the internals of Agent in this SDK, but I'm going to explain the reason why I was asking for a multi-agent roadmap and then see how you're building this. In ADK (agent development kit) by Google (Python library), you can define an agent with instructions and feed it a list of sub agents just like you did. My concern is that in ADK, those things share a state, so that tools can pick up certain pieces of configuration that might be required. (i.e. tenant ID). It also seemlessly shares the history and updates the state according to user and system prompts like so:

user: I want to create a report
agent -> delegates to report creating agent  (RC agent)
RC agent -> cool, I need the report type and title
user: the title is "XYZ"
agent -> knows it's still RC agent's task and delegates
RC agent -> still has the "title" in the state injected automagically, now requests: "I need the report type"
user: ...

You get the point, ADK allows to build multi-agent systems where state is automatically updated and injected and resolved once an agent is finished.

My question, is this what you're building, or is there additional work required? Is the state of the agents saved somewhere alongside the messages that resemble the message history?

[eznix86]

I know SubAgent technically extends Agent, but it doesn’t feel quite right to me. It’s still an Agent and can act independently, so calling it a SubAgent feels misleading.

Happy to hear Taylor’s thoughts on this.

Right, it could be confusing also for the community. I agree with you on this. I'll rename it to subAgents in a few. thanks @pushpak1300 for looking into it!

[eznix86]

@eznix86 Thanks for the effort, I know zero to none about the internals of Agent in this SDK, but I'm going to explain the reason why I was asking for a multi-agent roadmap and then see how you're building this. In ADK (agent development kit) by Google (Python library), you can define an agent with instructions and feed it a list of sub agents just like you did. My concern is that in ADK, those things share a state, so that tools can pick up certain pieces of configuration that might be required. (i.e. tenant ID). It also seemlessly shares the history and updates the state according to user and system prompts like so:

user: I want to create a report
agent -> delegates to report creating agent  (RC agent)
RC agent -> cool, I need the report type and title
user: the title is "XYZ"
agent -> knows it's still RC agent's task and delegates
RC agent -> still has the "title" in the state injected automagically, now requests: "I need the report type"
user: ...

You get the point, ADK allows to build multi-agent systems where state is automatically updated and injected and resolved once an agent is finished.

My question, is this what you're building, or is there additional work required? Is the state of the agents saved somewhere alongside the messages that resemble the message history?

I see what you mean here. Those subagents are stateless, so they only share "state" with the tasks given. So, it will be the job of the primary agent to give the tasks clearly. Thats where the prompt in instructions() should be well defined.

It would be more like this:

user: I want to create a final year report
agent -> delegates to report creating agent (while calling the subagent RC agent, sends tasks to that subagent) 
RC agent -> cool, I need the report type and title (returns back an output to the primary agent, then exits) 
---
agent:  whats report type and title ?
user: the title is "XYZ"
agent -> delegates tasks to RC agent with the report type and title
RC agent -> generate report, return to primary agent
agent -> here is your report
user: ...

the the flow is User -> agent -> subagent -> agent -> user. so the agent acts like the orchestrator/middleman.
To get this level of User -> subagent while talking to the primary agent -> user, we have to add this level of ADK with A2A like google does, and that's a lot of moving parts. I think it can still evolve. :) if this merges, the community can continuously add stuff until we get to that level.

[coreation]

Indeed, I'm appreciate the effort but alas have no time to get involved. For now I'll keep my ADK stack and keep a close eye on the AI SDK developments. Doesn't take away I'm blown away by the AI SDK, I'll use it for sure to drop in replace semantic chunking, embedding and direct OpenAI wrapper API calls.

[eznix86]

@pushpak1300 changed: agents() -> subAgents()

[JVillator0]

Hi! Just wanted to add a couple of thoughts to the discussion:

• Sharing context between parent + sub-agents: If the intention is for sub-agents to operate with the exact same conversation context as the parent agent, would it make sense to expose a messages() method (or similar) that points to the same underlying conversation/thread?

• Alternative model (sub-agents as tools): Another approach I’ve seen is treating sub-agents as tools. The AI SDK does this, in case it’s interesting to explore the pros/cons of that design:
  https://ai-sdk.dev/docs/agents/subagents#subagents

Curious what you think, especially around context ownership and how you want message/history to be shared (or isolated) across agents.

[taylorotwell]

I personally think you should just treat sub-agents as tools and be able to return an agent in the tools method just like a tool.

[eznix86]

@taylorotwell do you think it is the proper way of managing it in this PR ?

Or you have another thing in mind ?