Building an Agent Client App

From portal to code

Chat app vs agent app

Chat completions vs agent API

Feature	Chat App (Module 14)	Agent App (This Module)
API used	Chat Completions API	Responses API (Agents)
Can use tools?	No — text only	Yes — function calling, search, code
State management	You manage conversation history manually	Foundry manages conversations and state
Use case	Simple Q&A, summarisation, translation	Multi-step tasks, tool use, autonomous actions

Building an agent client: step by step

Step 1: Connect and get your agent

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint="https://your-project.services.ai.azure.com"
)

# Get the agents client
agents = client.agents

Step 2: Create a conversation and send a message

# Create a new conversation (thread)
response = agents.create_response(
    agent_id="your-agent-id",
    input="What's the refund policy for orders over $500?",
)

# Display the agent's response
print(response.output_text)

What’s happening:

• agent_id identifies which agent to talk to (found in the Foundry portal)
• input is the user’s message
• The agent automatically decides which tools to use
• output_text contains the final response after all tool calls complete

Step 3: Continue the conversation

# Send a follow-up message in the same conversation
response = agents.create_response(
    agent_id="your-agent-id",
    input="Can I get a refund for my order #12345?",
    previous_response_id=response.id  # Links to the previous conversation
)

print(response.output_text)

Key difference from chat apps: You don’t need to send the full conversation history. The previous_response_id tells Foundry to continue the same conversation — the agent remembers the context.

ℹ️ What happens behind the scenes

When you send a message to an agent, here’s what happens:

1. User message received — your app sends the input
2. Agent reasons — the LLM reads the input, instructions, and available tools
3. Tool selection — if needed, the agent decides which tool to call
4. Tool execution — Foundry runs the tool (search, code, API call)
5. Tool result — the tool returns data to the agent
6. Response generation — the agent generates a final response using the tool results
7. Response returned — your app receives the complete response

Steps 3-5 may repeat multiple times if the agent needs multiple tools.

Handling tool outputs in your app

Sometimes you want to see what tools the agent used:

response = agents.create_response(
    agent_id="your-agent-id",
    input="Look up order #12345 and tell me its status",
)

# Check what the agent did
for item in response.output:
    if item.type == "message":
        print(f"Agent said: {item.content[0].text}")
    elif item.type == "function_call":
        print(f"Agent called: {item.name} with {item.arguments}")

GreenLeaf scenario: GreenLeaf builds a client app where farmers can ask questions about their orders. The agent:

1. Receives: “Where’s my seed order?”
2. Calls: lookup_order function with the farmer’s ID
3. Calls: check_shipping function with the order number
4. Responds: “Your seed order #789 shipped yesterday via courier. Expected delivery: Thursday.”

🎬 Video walkthrough

Flashcards

Question

How is the agent API different from the chat completions API?

Click or press Enter to reveal answer

Answer

The agent API (Responses API) supports tool calling, automatic state management, and multi-step reasoning. Chat completions is text-only and requires you to manage conversation history manually.

Click to flip back

Question

How does an agent client maintain conversation context between messages?

Click or press Enter to reveal answer

Answer

By passing the previous_response_id from the last response. Unlike chat completions, you don't need to send the full message history — Foundry manages the conversation state.

Click to flip back

Question

What happens when an agent needs to use a tool to answer a question?

Click or press Enter to reveal answer

Answer

The agent: 1) Reasons about what tool to use, 2) Calls the tool with appropriate parameters, 3) Receives the tool result, 4) Generates a final response incorporating the tool output. This may repeat for multiple tools.

Click to flip back

Knowledge Check

Knowledge Check

Priya is building an agent client app. She notices that unlike her chat app (Module 14), she doesn't need to send the full conversation history with each message. Why?

AAgents have unlimited memory and never forgetBThe previous_response_id links messages in the same conversation, and Foundry manages the stateCAgent models are more powerful and can infer context without historyDThe system prompt contains all previous messages

Check Answer

Knowledge Check

GreenLeaf's agent client app receives the response after the agent looked up an order and checked shipping. Which part of the response object contains the agent's final answer to the user?

Aresponse.choices[0].message.content — same as chat completionsBresponse.output_text — the agent's final text responseCresponse.tool_calls — the list of tools the agent usedDresponse.system_prompt — the agent's instructions

Check Answer

---

Next up: Building a Text Analysis App — using Azure AI Language to extract insights from text.